home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 May: Tool Chest / Dev.CD May 98 TC.toast / Tool Chest / Development Kits / Instrumentation SDK / Instrumentation SDK 1.0.5 / Interfaces & Libraries / CIncludes / Instrumentation.h next >
Encoding:
C/C++ Source or Header  |  1997-07-08  |  7.9 KB  |  217 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Instrumentation.h
  3.  
  4.      Contains:    Trace and statistics collection interfaces for System 7 clients
  5.  
  6.      Version:    1.0
  7.  
  8.      Copyright:    © 1996 by Apple Computer, Inc.
  9.                  All rights reserved.
  10.  
  11. */
  12. #ifndef __INSTRUMENTATION__
  13. #define __INSTRUMENTATION__
  14.  
  15. #include <Types.h>
  16.  
  17. #ifdef __cplusplus
  18. extern "C" {
  19. #endif
  20.  
  21. #if PRAGMA_IMPORT_SUPPORTED
  22. #pragma import on
  23. #endif
  24.  
  25. #if PRAGMA_ALIGN_SUPPORTED
  26. #pragma options align=mac68k
  27. #endif
  28.  
  29. /*******************************************************************/
  30. /*                        Types                                       */
  31. /*******************************************************************/
  32. /* Reference to an instrumentation class */
  33. typedef struct InstOpaqueClassRef* InstClassRef;
  34.  
  35. /* Aliases to the generic instrumentation class for each type of class */
  36. typedef InstClassRef InstPathClassRef;
  37. typedef InstClassRef InstTraceClassRef;
  38. typedef InstClassRef InstHistogramClassRef;
  39. typedef InstClassRef InstSplitHistogramClassRef;
  40. typedef InstClassRef InstMagnitudeClassRef;
  41. typedef InstClassRef InstGrowthClassRef;
  42. typedef InstClassRef InstTallyClassRef;
  43.  
  44. /* Reference to a data descriptor */
  45. typedef struct InstOpaqueDataDescriptorRef* InstDataDescriptorRef;
  46.  
  47.  
  48. /*******************************************************************/
  49. /*            Constant Definitions                                 */
  50. /*******************************************************************/
  51.  
  52. /* Reference to the root of the class hierarchy */
  53. #define kInstRootClassRef     ( (InstClassRef) -1)
  54.  
  55. /* Options used for creating classes */
  56. typedef OptionBits InstClassOptions;
  57.  
  58. enum {
  59.     kInstDisableClassMask            = 0x00,            /* Create the class disabled */
  60.     kInstEnableClassMask            = 0x01,            /* Create the class enabled */
  61.  
  62.     kInstSummaryTraceClassMask        = 0x20            /* Create a summary trace class instead of a regular one */
  63. };
  64.  
  65. /* Options used for logging events*/
  66. typedef OptionBits InstEventOptions;
  67.  
  68. enum {
  69.     kInstStartEvent                    = 1,            /* This is a start event; begin accounting for an arc */
  70.     kInstEndEvent                    = 2,            /* This is an end event; stop accounting for an arc */
  71.     kInstMiddleEvent                = 3                /* This is a middle event */
  72. };
  73.  
  74. /* InstEventTag's are used to associate start, middle and end events */
  75. typedef UInt32 InstEventTag;
  76.  
  77. enum {
  78.     kInstNoEventTag                    = 0
  79. };
  80.  
  81. /*******************************************************************/
  82. /*                            API                                  */
  83. /*******************************************************************/
  84.  
  85.  
  86. /*********** Initialization and Termination routines (68K-only) ***********/
  87. #if GENERATING68K
  88.  
  89. extern pascal OSStatus        InstInitialize68K( void);
  90.  
  91. // You do not need to call this if your process calls ExitToShell().
  92. extern pascal OSStatus        InstTerminate68K( void);
  93.  
  94. #endif    //    GENERATING68K
  95.  
  96.  
  97. /*************************** Creation routines ***************************/
  98. /* Create a class that has no statistic or trace data. It is a path node in the class hierarchy */
  99. extern pascal OSStatus InstCreatePathClass( InstPathClassRef parentClass, const char *className, 
  100.                                             InstClassOptions options, InstPathClassRef *returnPathClass);
  101.  
  102. /*
  103.  Create a class that can log events to a trace buffer.
  104. */
  105. extern pascal OSStatus InstCreateTraceClass( InstPathClassRef parentClass, const char *className, 
  106.                                                 OSType component, InstClassOptions options, 
  107.                                                 InstTraceClassRef *returnTraceClass);
  108.  
  109. /*
  110.  Create a class that contains a histogram
  111. */
  112. extern pascal OSStatus InstCreateHistogramClass( InstPathClassRef parentClass, const char *className, 
  113.                                                     SInt32 lowerBounds, SInt32 upperBounds, UInt32 bucketWidth, 
  114.                                                     InstClassOptions options, InstHistogramClassRef *returnHistogramClass);
  115.  
  116. /*
  117.  Create a class that contains a split histogram
  118.  Split histograms are useful when examining a single range with two different
  119.  areas of different resolution.
  120. */
  121. extern pascal OSStatus InstCreateSplitHistogramClass( InstPathClassRef parentClass, const char *className, 
  122.                                                         SInt32 histogram1LowerBounds, UInt32 histogram1BucketWidth, 
  123.                                                         SInt32 knee, SInt32 histogram2UpperBounds, UInt32 histogram2BucketWidth, 
  124.                                                         InstClassOptions options, InstSplitHistogramClassRef *returnSplitHistogramClass);
  125.  
  126. /*
  127.  Create a class that has magnitude statistical data
  128. */
  129. extern pascal OSStatus InstCreateMagnitudeClass( InstPathClassRef parentClass, const char *className, 
  130.                                                 InstClassOptions options, InstMagnitudeClassRef *returnMagnitudeClass);
  131.  
  132. /*
  133.  Create a class that has growth statistical data
  134. */
  135. extern pascal OSStatus InstCreateGrowthClass( InstPathClassRef parentClass, const char *className, 
  136.                                               InstClassOptions options, InstGrowthClassRef *returnGrowthClass);
  137.  
  138. /*
  139.  Create a class that keeps tally statistics
  140. */
  141. extern pascal OSStatus InstCreateTallyClass( InstPathClassRef parentClass, const char *className, 
  142.                                                 UInt16 maxNumberOfValues, InstClassOptions options, 
  143.                                                 InstTallyClassRef *returnTallyClass);
  144.  
  145. /*
  146.  Create a descriptor to a piece of data
  147.  DataDescriptors must be used when logging trace data so that generic browsers can display the data.
  148. */
  149. extern pascal OSStatus InstCreateDataDescriptor( const char *formatString, InstDataDescriptorRef *returnDescriptor);
  150.  
  151. /* Create multiple Data Descriptors.  This is convenient when using static lists of format strings.*/
  152. extern pascal OSStatus InstCreateDataDescriptors( const char **formatStrings, ItemCount numberOfDescriptors, 
  153.                                                     InstDataDescriptorRef *returnDescriptorList);
  154.  
  155. /* Create a unique event tag.  These can be use to relate trace events.*/
  156. extern pascal InstEventTag InstCreateEventTag( void);
  157.  
  158. /*************************** Access routines ***************************/
  159.  
  160. /* Enable spooling for the given class node. */
  161. extern pascal OSStatus InstEnableClass( InstClassRef classRef);
  162.  
  163. /* Disable spooling for the given class node. */
  164. extern pascal OSStatus InstDisableClass( InstClassRef classRef);
  165.  
  166. /*************************** Dispose routines ***************************/
  167. extern pascal void InstDisposeClass( InstClassRef theClass);
  168.  
  169. extern pascal void InstDisposeDataDescriptor( InstDataDescriptorRef theDescriptor);
  170.  
  171. extern pascal void InstDisposeDataDescriptors( InstDataDescriptorRef *theDescriptorList, ItemCount numberOfDescriptors);
  172.  
  173. /*************************** Event Logging and Stat Updating routines ***************************/
  174. extern pascal void InstUpdateHistogram( InstHistogramClassRef theHistogramClass, SInt32 value, UInt32 count);
  175.  
  176. extern pascal void InstUpdateMagnitudeAbsolute( InstMagnitudeClassRef theMagnitudeClass, SInt32 newValue);
  177.  
  178. extern pascal void InstUpdateMagnitudeDelta( InstMagnitudeClassRef theMagnitudeClass, SInt32 delta);
  179.  
  180. extern pascal void InstUpdateGrowth( InstGrowthClassRef theGrowthClass, UInt32 increment);
  181.  
  182. extern pascal void InstUpdateTally( InstTallyClassRef theTallyClass, void *bucketID, UInt32 count);
  183.  
  184. /* Log a trace event that has no data */
  185. extern pascal void InstLogTraceEvent( InstTraceClassRef theTraceClass, InstEventTag eventTag, InstEventOptions options);
  186.  
  187. /* Log a trace event with data */
  188. extern pascal void InstLogTraceEventWithData( InstTraceClassRef theTraceClass, InstEventTag eventTag, 
  189.                                             InstEventOptions options, InstDataDescriptorRef theDescriptor, ...);
  190.  
  191. /*
  192.  The "dataStructure" should match the dataDescriptor's printf string.
  193.  All fields must be longword multiples.  ie, even char's (%c) or shorts (%d) must
  194.  be longwords in the data structure.
  195.  If the data structure contains a string, the string must be padded to be longword
  196.  aligned.
  197.  Think of this passing in a flattened version of printf varargs
  198. */
  199. extern pascal void InstLogTraceEventWithDataStructure( InstTraceClassRef theTraceClass, InstEventTag eventTag, 
  200.                                                         InstEventOptions options, InstDataDescriptorRef descriptorRef, 
  201.                                                         const UInt8 *dataStructure, ByteCount structureSize);
  202.  
  203. #if PRAGMA_ALIGN_SUPPORTED
  204. #pragma options align=reset
  205. #endif
  206.  
  207. #if PRAGMA_IMPORT_SUPPORTED
  208. #pragma import off
  209. #endif
  210.  
  211. #ifdef __cplusplus
  212. }
  213. #endif
  214.  
  215. #endif /* __INSTRUMENTATION__ */
  216.  
  217.